feat(theme): Add medium and high contrast theme by hristototov · Pull Request #5100 · callstack/react-native-paper

hristototov · 2026-09-03T10:05:02Z

Motivation

The theme only generates the MD3 standard contrast level. MD3 defines three levels, and the higher two exist for accessibility: they raise the contrast between text and background so the UI stays readable for users with low vision and in bright light. Without them, apps built with Paper have no supported way to meet the raised contrast ratios.

This adds the medium and high schemes for light and dark, and a contrast prop on PaperProvider to select them. standard stays the default and its colours do not change. It uses scripts/generate-contrast-tokens.ts

Measured against the baseline #6750A4 seed:

scheme	`primary` tone	`onPrimaryContainer` tone
light / standard	40.1	10.1
light / medium	26.7	100.0
light / high	13.3	86.9
dark / high	96.7	23.8

API

<PaperProvider contrast="high">
  <App />
</PaperProvider>

Related issue

Closes #5092

Test plan

Automated:

src/theme/__tests__/contrast.test.ts checks 17 text/background role pairs across both modes and both new levels, 64 pairs in total, and asserts >= 4.5 for medium and >= 7.0 for high. It also asserts that LightTheme and DarkTheme colours are unchanged.
src/core/__tests__/PaperProvider.test.tsx covers the contrast prop, the standard default, prop precedence over theme.contrast, and that a provider with only contrast set still follows the system color scheme.
No component snapshot colours changed. The only snapshot diff is the new contrast field on the serialized theme.

Manual, on an Android 12 emulator (API 31), using the new Contrast control in the example app drawer under Preferences:

Open the drawer, switch between Standard, Medium and High. Colours change at each step.
Toggle Dark Theme and repeat. All six combinations render correctly with no missing colours.
With "Use Dynamic Theme" on, note that Standard shows the wallpaper-based colours while Medium and High fall back to the contrast-correct scheme. This is the intended behaviour described above.
Restart the app. The selected level is restored from storage.

android-contrast.mov

ios-contrast.mov

…into hristototov/medium-and-high-contrast-theme

JKobrynski · 2026-09-04T12:15:18Z

+/** Only `standard` uses the reference palette steps. The other levels need
+ *  tones that are not in the palette, so they live in `./contrastSchemes`. */


These don't match MD3's published contrast schemes. On the color roles page, light/high primary is md.ref.palette.primary20 (#381E72), but this ships #312259; secondary, outline, outline-variant and on-surface-variant are off too, and surface-container isn't meant to change with contrast at all. Every tone MD3 asks for is already a key of ref/palette.ts - could roleToTone just gain medium and high maps, the way the old // extend with 'medium' | 'high' when those ship comment planned?

updated - I've removed the generator and hand-written the medium and high maps as you suggested.

JKobrynski · 2026-09-04T12:15:49Z

    return {
      ...base,
      ...props.theme,
+      contrast: level,


Passing a theme that has its own colors silently overrides the contrast scheme, but theme.contrast still reports the level you asked for - so useTheme().contrast says "high" while the colours on screen are standard. Worth reconciling, given the docs tell people to read the level back off the theme.

Good catch. The behaviour is intentional but was undocumented, which is the actual problem: contrast records which scheme was selected, and anything passed via theme.colors is layered on top, so an override survives a contrast change.

I've added code comments making that explicit.

JKobrynski · 2026-09-04T12:16:42Z

-        ? DarkTheme
-        : LightTheme;
+      ? getDynamicTheme(isDarkMode, contrast)
+      : createTheme({ dark: isDarkMode, contrast });


This builds a new theme object on every render, so the provider rebuilds the theme and every themed component re-renders with it. getTheme(isDarkMode, contrast) returns the cached one worth using that here?

JKobrynski · 2026-09-04T12:23:52Z

And we've got conflicts

…into hristototov/medium-and-high-contrast-theme # Conflicts: # src/core/PaperProvider.tsx # src/index.tsx

satya164 · 2026-09-09T14:39:45Z

+      primaryFixedDim: 'primary80',
+      onPrimaryFixed: 'primary10',
+      onPrimaryFixedVariant: 'primary30',


I get a contrast ratio of 5.47:1 for onPrimaryFixedVariant (#4F378B) on primaryFixedDim (#D0BCFF), below the documented 7:1 target for high contrast. The dark/high mapping at lines 311-313 uses the same values. Could we adjust this pair and include it in the contrast assertions? CONTRAST_PAIRS currently checks onPrimaryFixed on primaryFixed, so it misses this combination.

satya164 · 2026-09-09T14:39:45Z

+      secondaryFixedDim: 'secondary80',
+      onSecondaryFixed: 'secondary10',
+      onSecondaryFixedVariant: 'secondary30',


I get 5.45:1 for onSecondaryFixedVariant (#4A4458) on secondaryFixedDim (#CCC2DC), below the documented 7:1 high-contrast target. The dark/high mapping at lines 315-317 has the same issue. Could we adjust this pair and cover it in the contrast assertions as well?

satya164 · 2026-09-09T14:39:45Z

+      tertiaryFixedDim: 'tertiary80',
+      onTertiaryFixed: 'tertiary10',
+      onTertiaryFixedVariant: 'tertiary30',


I get 5.49:1 for onTertiaryFixedVariant (#633B48) on tertiaryFixedDim (#EFB8C8), below the documented 7:1 high-contrast target. The dark/high mapping at lines 319-321 has the same issue. Could we adjust this pair and cover it in the contrast assertions as well? The test that requires all fixed colors to stay unchanged across contrast levels would also need to be revised.

satya164

Any additional themes should just be exported theme objects, e.g.:

MediumContrastLightTheme
MediumContrastDarkTheme
HighContrastLightTheme
HighContrastDarkTheme

Similarly there can be variants for dynamic themes.

It's a much simpler concept since we already export themes and accept theme prop, and there's no need for additional helpers and utilities. "Building" a theme object with createTheme({ dark: true, contrast: 'high' }) instead of just importing HighContrastDarkTheme is unnecessary indirection.

Hristo Totov added 2 commits September 3, 2026 12:53

feat(theme): add medium and high contrast levels

83648aa

Merge branch 'main' of https://github.com/callstack/react-native-paper …

bcce161

…into hristototov/medium-and-high-contrast-theme

hristototov self-assigned this Sep 3, 2026

hristototov added the v6 label Sep 3, 2026

github-actions Bot added the Contributor: Internal label Sep 3, 2026

hristototov requested review from adrcotfas and satya164 and removed request for satya164 September 3, 2026 11:38

JKobrynski reviewed Sep 4, 2026

View reviewed changes

Hristo Totov added 2 commits September 6, 2026 19:24

Merge branch 'main' of https://github.com/callstack/react-native-paper …

15a6cc5

…into hristototov/medium-and-high-contrast-theme # Conflicts: # src/core/PaperProvider.tsx # src/index.tsx

fix(): adress cr comments

03c403b

hristototov requested a review from JKobrynski September 6, 2026 16:33

satya164 reviewed Sep 9, 2026

View reviewed changes

satya164 requested changes Sep 9, 2026

View reviewed changes

Navigation Menu

Uh oh!

Uh oh!

feat(theme): Add medium and high contrast theme - #5100

feat(theme): Add medium and high contrast theme#5100
hristototov wants to merge 4 commits into
mainfrom
hristototov/medium-and-high-contrast-theme

hristototov commented Sep 3, 2026 •

edited

Loading

Uh oh!

JKobrynski Sep 4, 2026

Uh oh!

hristototov Sep 6, 2026

Uh oh!

JKobrynski Sep 4, 2026

Uh oh!

hristototov Sep 6, 2026

Uh oh!

JKobrynski Sep 4, 2026 •

edited

Loading

Uh oh!

hristototov Sep 6, 2026

Uh oh!

JKobrynski commented Sep 4, 2026

Uh oh!

satya164 Sep 9, 2026

Uh oh!

satya164 Sep 9, 2026

Uh oh!

satya164 Sep 9, 2026

Uh oh!

satya164 left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		/** Only `standard` uses the reference palette steps. The other levels need
		* tones that are not in the palette, so they live in `./contrastSchemes`. */

Uh oh!

Uh oh!

Conversation

hristototov commented Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Related issue

Test plan

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JKobrynski Sep 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JKobrynski commented Sep 4, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

satya164 left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

hristototov commented Sep 3, 2026 •

edited

Loading

JKobrynski Sep 4, 2026 •

edited

Loading